⚠️ This PR is missing a Discord Discussion URL in the body.

All PRs must reference a prior Discord discussion to ensure community alignment before implementation.

Please edit the PR description to include a link like:

Discord Discussion URL: https://discord.com/channels/...

This PR will be automatically closed in 3 days if the link is not added.

🔍 Four Monks Consolidated Review — PR #683

Reviewers: 超渡法師 · 普渡法師 · 擺渡法師 · 覺渡法師

Consensus Verdict: Request Changes 🔴

🔴 SUGGESTED CHANGES

1. Hidden policy expansion — Conventional Commits title gate should be a separate PR (擺渡法師)

   • This PR is titled docs-required-check, but it also introduces a repo-wide Conventional Commits title validation (lines 16-24). There is no existing title-check workflow on main.
   • Merging this would silently enforce a new policy on all PRs, not just fix/feat ones. This should be split into its own PR with explicit discussion.

2. Mandatory docs update for all fix/feat PRs is too strict (all four monks agree)

   • Many legitimate bug fixes (typo corrections, race conditions, off-by-one errors) do not warrant documentation changes. This will lead to meaningless docs churn.
   • Suggestions:
     • Change to a warning (continue-on-error: true + ::warning::) instead of a hard failure
     • Or switch the escape hatch to a label-based mechanism (e.g., docs-not-required label) — more visible and manageable than a keyword buried in the PR body
     • Or auto-exempt PRs that only touch tests/ or scripts/ directories

3. Workflow Command Injection risk with echo "$PR_BODY" (覺渡法師)

   • If $PR_BODY contains GitHub Actions workflow commands (e.g., ::set-output, ::stop-commands::), they could be interpreted by the Runner when piped through echo.
   • Suggested fix — use Bash built-in matching instead:

     if [[ "$PR_BODY" =~ skip-docs-check ]]; then
       echo "⏭️ skip-docs-check found in PR body, skipping docs check."
       exit 0
     fi

🟡 NIT

4. SHA values should go through env: for consistency (普渡法師)

   • ${{ github.event.pull_request.base.sha }} and head.sha are directly interpolated in the run: block. While hex SHAs are not injectable, this is inconsistent with the env: pattern used for PR_TITLE and PR_BODY.
   • Suggested fix:

     env:
       BASE_SHA: ${{ github.event.pull_request.base.sha }}
       HEAD_SHA: ${{ github.event.pull_request.head.sha }}
     run: |
       DOCS_CHANGED=$(git diff --name-only "${BASE_SHA}...${HEAD_SHA}" -- docs/ | wc -l)

5. Use printf instead of echo for user-controlled strings (覺渡法師)

   • echo "$PR_TITLE" behaves unpredictably if the title starts with -e or -n. Use printf '%s\n' "$PR_TITLE" instead.

6. Workflow display name vs filename mismatch (超渡法師, 普渡法師)

   • name: PR Title & Docs Check does not match docs-required-check.yml — consider aligning for discoverability in the Actions tab.

7. Missing Discord Discussion URL in PR body (bot already flagged).

🟢 INFO

• Using env: + shell variable quoting for PR_TITLE and PR_BODY is the correct GitHub-recommended pattern for script injection prevention. ✅
• fetch-depth: 0 ensures git diff works correctly across branches. ✅
• The skip-docs-check escape hatch concept is good, but the implementation mechanism should be improved (see above).

📝 Four Monks Review — TL;DR Update

This PR should be split or narrowed. The current workflow mixes a new global title policy with an overly strict docs gate, while the previously suspected injection issue is not a confirmed security bug under GitHub's recommended env pattern.

Action Items for Contributor

1. Split or remove the Conventional Commits title validation — it is an undisclosed repo-wide policy change that deserves its own PR and discussion
2. Soften the docs gate — change from hard failure to warning, adopt label-based exemption (e.g., docs-not-required), or narrow the scope to sensitive file changes rather than blanket fix/feat enforcement
3. Minor hardening (non-blocking): move SHA values to env: block for consistency, prefer printf over echo for user-controlled strings

Full analysis in the previous comment.

OpenAB PR Screening

This is auto-generated by the OpenAB project-screening flow for context collection and reviewer handoff.
Click 👍 if you find this useful. Human review will be done within 24 hours. We appreciate your support and contribution 🙏

• Title: chore: add docs-required-check workflow for fix/feat PRs
• Source: chore: add docs-required-check workflow for fix/feat PRs #683
• Status: moved to PR-Screening
• Generated at: 2026-05-02T10:49:39.703Z
• Discord thread: https://discord.com/channels/1488041051187974246/1500086699663818832